React useFormStatus: Kattava opas lomakkeiden tilanhallintaan

React 18:ssa esitelty useFormStatus-hook tarjoaa tehokkaan ja suorituskykyisen tavan hallita lomakkeiden lähetystilaa React Server Components -komponenteissa. Tämä hook on suunniteltu erityisesti toimimaan palvelintoimintojen (server actions) kanssa, tarjoten saumattoman integraation lomakkeiden lähetysten käsittelyyn suoraan palvelimella. Se yksinkertaistaa lomakkeen lähetyksen tilan seurantaa ja antaa arvokasta tietoa, kuten onko lomake odotustilassa, onnistuiko lähetys vai kohtasiko se virheen. Tämä opas tutkii useFormStatus-hookin ominaisuuksia, sen etuja ja käytännön esimerkkejä, jotka näyttävät sen käytön eri tilanteissa.

Palvelintoimintojen ja useFormStatus-hookin ymmärtäminen

Ennen kuin syvennymme useFormStatus-hookiin, on tärkeää ymmärtää React Server Components ja palvelintoiminnot (Server Actions). Palvelintoiminnot mahdollistavat palvelimella suoritettavien funktioiden määrittelyn, jotka ovat suoraan käytettävissä React-komponenteistasi. Tämä mahdollistaa lomakkeiden lähetysten, datan noudon ja muiden palvelinpuolen operaatioiden käsittelyn ilman erillistä API-rajapintaa.

useFormStatus-hook tarjoaa sitten tietoa näiden lomakkeiden lähetysten käynnistämien palvelintoimintojen suorituksesta.

Mikä on useFormStatus?

useFormStatus on React-hook, joka palauttaa objektin, joka sisältää tietoa viimeisimmän lomakkeen lähetyksen tilasta. Nämä tiedot sisältävät:

• pending: Boolean-arvo, joka ilmaisee, onko lomaketta parhaillaan lähettämässä.
• data: Lähetykseen liittyvä FormData-objekti.
• method: Lähetyksessä käytetty HTTP-metodi (tyypillisesti 'POST').
• action: Käynnistetty palvelintoimintofunktio (Server Action).

useFormStatus-hookin käytön edut

useFormStatus-hookin hyödyntäminen tarjoaa useita keskeisiä etuja:

• Yksinkertaistettu tilanhallinta: Poistaa tarpeen manuaaliselle tilanhallinnalle lomakkeen lähetystilan seuraamiseksi. Hook päivittyy automaattisesti lähetyksen edetessä.
• Parempi käyttökokemus: Tarjoaa reaaliaikaista palautetta käyttäjille, kuten latausindikaattoreiden näyttäminen lomaketta käsiteltäessä tai virheilmoitusten näyttäminen epäonnistumisen yhteydessä.
• Siisti koodi: Edistää deklaratiivisempaa ja ylläpidettävämpää koodipohjaa erottamalla lomakkeen lähetyslogiikan komponentin renderöinnistä.
• Saumaton integraatio palvelintoimintojen kanssa: Suunniteltu toimimaan täydellisesti palvelintoimintojen kanssa, mikä tekee lomakkeiden lähetysten käsittelystä suoraan palvelimella helppoa.

Käytännön esimerkkejä useFormStatus-hookin käytöstä

Katsotaanpa useita käytännön esimerkkejä, jotka havainnollistavat useFormStatus-hookin käyttöä eri tilanteissa.

Peruslomakkeen lähetys latausindikaattorilla

Tämä esimerkki näyttää yksinkertaisen lomakkeen, jossa on latausindikaattori, joka näytetään lomaketta lähetettäessä.

Palvelintoiminto (actions.js):

'use server'

export async function submitForm(formData) {
  // Simuloidaan viivettä lataustilan demonstroimiseksi
  await new Promise(resolve => setTimeout(resolve, 2000));

  const name = formData.get('name');
  console.log('Lomake lähetetty nimellä:', name);
  return { message: `Lomake lähetetty onnistuneesti nimellä: ${name}` };
}

React-komponentti (FormComponent.jsx):

'use client'

import { useFormStatus } from 'react-dom'
import { submitForm } from './actions'

function FormComponent() {
  const { pending } = useFormStatus()

  return (
    

      Nimi:
      
      
        {pending ? 'Lähetetään...' : 'Lähetä'}
      
    
  )
}

export default FormComponent

Tässä esimerkissä useFormStatus-hookin pending-ominaisuutta käytetään syöttökentän ja painikkeen poistamiseen käytöstä lomakkeen lähetyksen aikana sekä "Lähetetään..."-viestin näyttämiseen.

Onnistumis- ja virhetilojen käsittely

Tämä esimerkki näyttää, kuinka onnistumis- ja virhetiloja käsitellään lomakkeen lähetyksen jälkeen.

Palvelintoiminto (actions.js):

'use server'

export async function submitForm(formData) {
  // Simuloidaan viivettä
  await new Promise(resolve => setTimeout(resolve, 2000));

  const name = formData.get('name');

  if (!name) {
    throw new Error('Nimi vaaditaan');
  }

  console.log('Lomake lähetetty nimellä:', name);
  return { message: `Lomake lähetetty onnistuneesti nimellä: ${name}` };
}

React-komponentti (FormComponent.jsx):

'use client'

import { useFormStatus } from 'react-dom'
import { submitForm } from './actions'
import { useState } from 'react'

function FormComponent() {
  const { pending } = useFormStatus()
  const [message, setMessage] = useState(null);
  const [error, setError] = useState(null);

  async function handleSubmit(formData) {
    try {
      const result = await submitForm(formData);
      setMessage(result.message);
      setError(null);
    } catch (e) {
      setError(e.message);
      setMessage(null);
    }
  }

  return (
    

      Nimi:
      
      
        {pending ? 'Lähetetään...' : 'Lähetä'}
      
      {pending && 
Lähetetään...
}
      {message && 
{message}
}
      {error && 
Virhe: {error}
}
    
  )
}

export default FormComponent

Tässä esimerkissä handleSubmit-funktiossa käytetään try/catch-lohkoa. Jos palvelintoiminto heittää virheen, se otetaan kiinni ja näytetään käyttäjälle. Onnistumisviesti näytetään onnistuneen lähetyksen jälkeen.

FormData:n käyttäminen monimutkaiselle datalle

useFormStatus toimii saumattomasti FormData:n kanssa, mikä mahdollistaa monimutkaisten tietorakenteiden helpon käsittelyn. Tässä on esimerkki tiedostojen lataamisesta.

Palvelintoiminto (actions.js):

'use server'

export async function uploadFile(formData) {
  // Simuloidaan tiedoston käsittelyä
  await new Promise(resolve => setTimeout(resolve, 2000));

  const file = formData.get('file');

  if (!file) {
    throw new Error('Tiedostoa ei ladattu');
  }

  console.log('Tiedosto ladattu:', file.name);
  return { message: `Tiedosto ladattu onnistuneesti: ${file.name}` };
}

React-komponentti (FormComponent.jsx):

'use client'

import { useFormStatus } from 'react-dom'
import { uploadFile } from './actions'
import { useState } from 'react'

function FormComponent() {
  const { pending } = useFormStatus()
  const [message, setMessage] = useState(null);
  const [error, setError] = useState(null);

  async function handleSubmit(formData) {
    try {
      const result = await uploadFile(formData);
      setMessage(result.message);
      setError(null);
    } catch (e) {
      setError(e.message);
      setMessage(null);
    }
  }

  return (
    

      Lataa tiedosto:
      
      
        {pending ? 'Ladataan...' : 'Lataa'}
      
      {pending && 
Ladataan...
}
      {message && 
{message}
}
      {error && 
Virhe: {error}
}
    
  )
}

export default FormComponent

Tämä esimerkki näyttää, kuinka tiedostojen latauksia käsitellään FormData:n avulla. Palvelintoiminto hakee tiedoston FormData-objektista ja käsittelee sen. useFormStatus-hook hallitsee lataustilaa tiedoston latauksen aikana.

Parhaat käytännöt useFormStatus-hookin käyttöön

Saadaksesi suurimman hyödyn useFormStatus-hookista, harkitse näitä parhaita käytäntöjä:

• Anna selkeää käyttäjäpalautetta: Käytä pending-tilaa näyttääksesi informatiivisia latausindikaattoreita ja poistaaksesi lomakkeen elementit käytöstä estääksesi useita lähetyksiä.
• Käsittele virheet siististi: Toteuta virheenkäsittely napataksesi poikkeukset palvelintoiminnoissasi ja näytä käyttäjäystävällisiä virheilmoituksia.
• Validoi data palvelimella: Suorita palvelinpuolen validointi varmistaaksesi datan eheyden ja turvallisuuden.
• Pidä palvelintoiminnot ytimekkäinä: Keskity palvelintoiminnoissa tiettyihin tehtäviin parantaaksesi suorituskykyä ja ylläpidettävyyttä.
• Huomioi saavutettavuus: Varmista, että lomakkeesi ovat saavutettavia tarjoamalla asianmukaiset selitteet (labels), ARIA-attribuutit ja näppäimistönavigoinnin tuen.

Edistyneet käyttötapaukset

Perusesimerkkien lisäksi useFormStatus-hookia voidaan käyttää monimutkaisemmissa skenaarioissa:

• Progressiivinen parantaminen: Käytä palvelintoimintoja ja useFormStatus-hookia parantaaksesi lomakkeitasi asteittain, tarjoten peruskokemuksen käyttäjille, joilla JavaScript on poissa käytöstä, ja rikkaamman kokemuksen niille, joilla se on käytössä.
• Optimistiset päivitykset: Toteuta optimistisia päivityksiä päivittämällä käyttöliittymä heti lomakkeen lähetyksen jälkeen olettaen, että lähetys onnistuu. Peruuta päivitys, jos lähetys epäonnistuu.
• Integrointi lomakekirjastojen kanssa: Integroi useFormStatus suosittujen lomakekirjastojen, kuten Formikin tai React Hook Formin, kanssa hallitaksesi lomakkeen tilaa ja validointia. Vaikka näillä kirjastoilla on usein oma tilanhallintansa, useFormStatus voi olla hyödyllinen lopullisessa lähetysvaiheessa palvelintoimintoon.

Kansainvälistämisen (i18n) huomioiminen

Kun rakennetaan lomakkeita maailmanlaajuiselle yleisölle, kansainvälistäminen (i18n) on ratkaisevan tärkeää. Tässä on, miten voit huomioida i18n:n käyttäessäsi useFormStatus-hookia:

• Lokalisoidut virheilmoitukset: Varmista, että käyttäjälle näytettävät virheilmoitukset on lokalisoitu heidän haluamalleen kielelle. Tämä voidaan saavuttaa tallentamalla virheilmoitukset käännöstiedostoihin ja käyttämällä kirjastoa, kuten react-intl tai i18next, oikean käännöksen noutamiseen.
• Päivämäärän ja numeroiden muotoilu: Käsittele päivämäärän ja numeroiden muotoilu käyttäjän kieliasetusten (locale) mukaisesti. Käytä kirjastoja, kuten Intl.DateTimeFormat ja Intl.NumberFormat, näiden arvojen oikeaan muotoiluun.
• Oikealta-vasemmalle (RTL) -tuki: Jos sovelluksesi tukee kieliä, joita kirjoitetaan oikealta vasemmalle (esim. arabia, heprea), varmista, että lomakkeesi on tyylitelty oikein RTL-asettelujen huomioon ottamiseksi.
• Lomakkeen validointi: Räätälöi lomakkeen validointisäännöt eri kieliasetuksille. Esimerkiksi puhelinnumeron validointi voi vaihdella merkittävästi maiden välillä.

Esimerkki lokalisoiduista virheilmoituksista:

// translations/en.json
{
  "form.error.nameRequired": "Please enter your name.",
  "form.success.submission": "Thank you for your submission!"
}

// translations/fi.json
{
  "form.error.nameRequired": "Syötä nimesi.",
  "form.success.submission": "Kiitos lähetyksestäsi!"
}

// Komponentti, joka käyttää react-intl:ää
import { useIntl } from 'react-intl';

function FormComponent() {
  const intl = useIntl();
  const [error, setError] = useState(null);

  // ...

  catch (e) {
    setError(intl.formatMessage({ id: 'form.error.nameRequired' }));
  }
}

Saavutettavuusnäkökohdat

Saavutettavuus on keskeinen osa inklusiivisten verkkosovellusten rakentamista. Tässä on useita saavutettavuusnäkökohtia, jotka on hyvä pitää mielessä useFormStatus-hookia käytettäessä:

• ARIA-attribuutit: Käytä ARIA-attribuutteja antaaksesi avustaville teknologioille tietoa lomakkeen tilasta. Käytä esimerkiksi aria-busy="true"-attribuuttia lähetyspainikkeessa, kun lomake on odotustilassa.
• Selitteet (Labels): Varmista, että kaikilla lomakekentillä on selkeät ja kuvaavat selitteet, jotka on yhdistetty syöte-elementteihin <label>-elementin avulla.
• Virheilmoitukset: Näytä virheilmoitukset tavalla, joka on helposti huomattavissa ja ymmärrettävissä vammaisille käyttäjille. Käytä ARIA-attribuutteja, kuten aria-live="assertive", ilmoittaaksesi virheilmoituksista ruudunlukijoille.
• Näppäimistönavigointi: Varmista, että käyttäjät voivat navigoida lomakkeella pelkällä näppäimistöllä. Käytä tabindex-attribuuttia hallitaksesi elementtien fokusjärjestystä.
• Värikontrasti: Varmista, että lomakkeessa käytetyillä tekstin ja taustan väreillä on riittävä kontrasti, jotta ne ovat helposti luettavissa käyttäjille, joilla on näkövamma.

useFormStatus vs. perinteinen tilanhallinta

Perinteisesti React-kehittäjät ovat hallinneet lomakkeiden lähetystilaa komponentin tilalla (useState) tai monimutkaisemmilla tilanhallintakirjastoilla (esim. Redux, Zustand). Tässä on vertailu näiden lähestymistapojen ja useFormStatus-hookin välillä:

Ominaisuus	useFormStatus	useState	Ulkoinen tilanhallinta
Monimutkaisuus	Matala	Keskitaso	Korkea
Integraatio palvelintoimintojen kanssa	Saumaton	Vaatii manuaalisen integraation	Vaatii manuaalisen integraation
Toistuva koodi (Boilerplate)	Minimaalinen	Kohtalainen	Merkittävä
Sopivat käyttötapaukset	Lomakkeet, jotka lähettävät suoraan palvelintoimintoihin	Yksinkertaiset lomakkeet rajoitetulla tilalla	Monimutkaiset lomakkeet, joilla on jaettu tila komponenttien välillä

useFormStatus loistaa, kun lomakkeesi ovat suorassa vuorovaikutuksessa Reactin palvelintoimintojen kanssa. Se vähentää toistuvaa koodia ja yksinkertaistaa prosessia. Kuitenkin erittäin monimutkaisissa lomakkeissa, joiden tila on jaettu useiden komponenttien kesken, täysimittainen tilanhallintakirjasto voi silti olla perusteltu.

Yleisten ongelmien vianmääritys

Tässä on joitakin yleisiä ongelmia, joita saatat kohdata käyttäessäsi useFormStatus-hookia, ja kuinka niitä voi ratkaista:

• useFormStatus ei päivity:
  • Varmista, että käytät useFormStatus-hookia <form>-elementin sisällä, jonka action-props on asetettu palvelintoimintoon.
  • Tarkista, että palvelintoiminto on määritelty ja exportattu oikein.
  • Tarkista, onko palvelintoiminnossa virheitä, jotka saattavat estää sen onnistuneen suorituksen.
• Virheilmoitukset eivät näy:
  • Varmista, että nappaat virheet oikein palvelintoiminnossasi ja palautat virheilmoituksen.
  • Varmista, että näytät virheilmoituksen komponentissasi käyttämällä error-tilaa.
• Latausindikaattori ei tule näkyviin:
  • Varmista, että käytät useFormStatus-hookin pending-tilaa näyttääksesi latausindikaattorin ehdollisesti.
  • Tarkista, että palvelintoiminnon suoritus todella kestää jonkin aikaa (esim. simuloimalla viivettä).

Yhteenveto

useFormStatus tarjoaa siistin ja tehokkaan tavan hallita lomakkeiden lähetystilaa React-sovelluksissa, jotka käyttävät palvelinkomponentteja. Hyödyntämällä tätä hookia voit yksinkertaistaa koodiasi, parantaa käyttökokemusta ja integroitua saumattomasti palvelintoimintoihin. Tämä opas on käsitellyt useFormStatus-hookin perusteet, tarjonnut käytännön esimerkkejä ja käsitellyt parhaita käytäntöjä sen tehokkaaseen käyttöön. Sisällyttämällä useFormStatus-hookin React-projekteihisi voit tehostaa lomakkeiden käsittelyä ja rakentaa vankempia ja käyttäjäystävällisempiä sovelluksia maailmanlaajuiselle yleisölle.